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1 I n troduction 

P 1 i n k - 1 I is a Phoenix Software Associates Ltd. software 
system that can hind together individually compiled modules of a 
program into a single file that may be loaded and executed by the 
operating system. It runs on a Z80 ( * ) micro- processor under any 
of the CP/M (*) compatible operating systems. 

Plink-II will accept PSA and Microsoft relocatable files as 
input (some Microsoft variants are accepted also: see Appendix). 
Plink-II offers complete control over the memory utilization of 
the program, including the ability to create arbitrary overlay 
structures . 

Library files consisting of many separately compiled modules 
may be used as input. Plink-II offers methods for including all 
or only the required modules of a library into the program. 

Plink-II is a two -pass linkage editor. That is, each of the 
input files is read twice. Since the output file is built up on 
disk, Plink-II has the ability to create 6 4K programs that 
completely fill the address space of the machine, unlike other 
linkage editors which require that the output file share memory 
space with them and their tables. It is even possible to use a 
small machine to create programs intended for execution on a 
1 a r g e r one. A double disk buffering scheme insures adequate 
e x e c ut ion speed. When overlays are used, programs consisting o f 
up to 4 megabytes of code may be created. 

There are many advantages to the practice of linking 
together separately compiled modules instead of working with a 
single, large program. A large program may be decomposed into 
small modules which may be edited and compiled more quickly. 
Indeed, most compilers available for the Z80 can only handle 
modules of a limited size, and create output files that require 
linking before use. 

For example, to correct a bug, the programmer need only 
re-compile the affected modules and r e - 1 i n k the program, instead 
of re-compiling the entire program. The linkage process is much 
f a s t e r than compilation. 

It often happens that a routine is used in several programs, 
a special I/O routine or COSINE function, for example. Instead 
of copying the source code for this routine into each program, it 
may be compiled once and then linked in wherever it may be 
required. Furthermore, using Plink-II, routines generated with 
different compilers may be combined into a single program. The 
programmer can gradually build up a library of general purpose 
routines and avoid the useless effort of solving the same 
programming problems over and over again. 
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Using a linkage editor eases the problems encountered when 
several programmers must work together on a large program. Once 
the programming problem has been broken down into separate 
modules, each programmer may work relatively independently. 

The remainder of this guide describes how to use Plink-II. 
An overview of Plink-II concepts and operation is offered In 
section 2. The following sections describe Plink-II input 
statements. The manual is designed to be read sequentially, with 
side-issues deferred to appendices. The reader should have as 
background some simple programming experience. 


( * ) Z 80 is a trademark of Zilog. 

(*) CP/M is a trademark of Digital Research Corporation. 
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2 Overview of Plink-II Concepts 

Plink-II accepts as input RELOCATABLE or REL files. These 
are the files that are created by most compilers and assemblers. 
The term "relocatable" refers to the fact that the machine code 
in these files may be "relocated" by the linkage editor; that is, 
the code can be modified to execute at any memory address in the 
computer. Thus, the programmer is freed from having to choose 
memory locations himself, and the same code can be loaded at 
different addresses in different programs. 

Each REL file may contain one or more MODULES. A MODULE is 
the relocatable code output by the compiler or assembler for a 
program unit (e.g. Fortran subroutine). REL files containing 
more than one module are referred to as LIBRARYs. Typically, a 
manufacturer of a compiler will supply a Library along with it 
which contains I/O, math, and other support routines needed by 
the programs compiled in that language. Since the routines are 
kept in separate modules, Plink can select only those modules 
that are required by a particular program, thus keeping program 
size to a m i n u m u m . 

Each module has a name. Modules with the same name may be 
included in the same program, but there are several statements 
that use the module name, and these will refer to a randomly 
selected module if there are duplicates. In the PSA Assembler, 
the .IDEM! pseudo operation is used to declare the module name. 
Its use is highly recommended, as the default module name is 
".MAIN.", and duplicate module names will result if more than one 
of these modules is used. The available compilers for the Z80 
all generate a module name automatically. 

Each module is made up of SEGMENTS (also called "relocation 
bases"). Segments are the basic units of code and/or data 
involved in the linkage edit. After Plink-II is aware of what 
modules are to be included in the program, it assigns memory 
addresses to each segment in each module. Any code in each 
segment is relocated so that it will execute at the address to 
which it is assigned. 

Several kinds of segments may be contained in a module, and 
they all have names that may be referred to during the linkage 
edit. The main code segment, usually containing all of the 
executable code in the module, has the same name as the module 
itself. The main data segment of each module also has the same 
name a3 the module, preceded by a double quote ("). For example, 
a module named ARCTAN would contain a code segment named ARCTAN 
and a data segment named "ARCTAN (here duplicate module names 
result in duplicate segment names). 

All of the other segments in each module are COMMON blocks. 
One of these segments is named " . B L N K . " , and is referred to as 
the "unlabeled common". This is the common block that will be 
created by FORTRAN compilers when the programmer doesn't supply a 
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specific name for a common block. Other common blocks have names 
specified by the programmer. 

Common blocks typically contain only data, and by default, 
all common block3 of the same name share the same memory space. 
In other words, this is a method for defining a block of data 
that may be shared among several modules. Unlike many other 
linkage editors, Plink-II doesn't require commons of the same 
name to be of the same size, or require that the module declaring 
the largest size be linked first : it simply allocates the maximum 
space needed. 

The CONCATENATE statement changes a common block so that the 
memory space is not shared: each module is allocated its own 
space within the common. This is useful for tasks such as 
creating tables where each module contributes a single table 
entry. 


A SYMBOL is a name given to a particular address within a 
segment (a RELATIVE symbol) or to some 16-bit number (an ABSOLUTE 
symbol). One of the major features of the linkage edit process 
is t h at each separately compiled module may access symbols 
defined in other modules. An INTERNAL symbol is one whose 
address is available to modules other than the one in which it is 
defined. Module symbols which are not INTERNAL are invisible to 
other modules. An EXTERNAL symbol is one which is used in a 
module, but is defined elsewhere. All EXTERNAL, r e f e r e n c e s must 
be satisfied by INTERNAL declarations in another module, or the 
symbols must be defined in some other fashion. 

An ENTRY point is an INTERNAL symbol which comes into play 
during a library search. In this mode of operation only those 
library modules having ENTRY points which are referenced as 
EXTERNAL symbols by one or more already linked modules are 
included in the p r o g r a m (see the SEARCH and LIBRARY statements). 

Duplicate symbols (having the same name) are allowed, but 
the first definition encountered is used. A warning message is 
given for the others. 

Plink-II offers a great deal of control over how the module 
segments are arranged in memory. By default, segments are 
allocated bo the next available space, but the LOCATE statement 
may be used to cause subsequent allocations to be made at a 
higher address. Segments that form a contiguous unit in memory 
are organized into SECTIONS. Also, each program overlay is a 
SECTION. 

To sum up, the output of a compiler or assembler is a 
MODULE. One or modules make up a REL file. Plink-II decomposes 
the MODULES into SEGMENTS, re- groups the SEGMENTS into SECTIONS, 
and organizes the SECTIONS into the output program. In the 
following section, the commands required to carry out these tasks 
are described i n d e t ail . 
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3 Plink-II Input Format 

The following sections describe some basic input elements. 
Later sections show how these are combined to create full 
statements. An appendix gives an abbreviated BNF syntax for 
those familiar with formal languages. 

3.1 Literals 

A LITERAL is a sequence of characters delimited by single 
quotes ('). If a quote may be placed in a literal by using two 
quotes. Here are some valid literals: 


'This is a literal' 

'This literal contains a ' ' character' 


Literals are limited to a length of 128 characters, and must 
be entered on a single input line. 

3.2 16-bit Values 

A 16-bit value may be expressed as a number, or as a literal 
of one or two characters, for example: 'VI'. If a single 

character is used, its value is formed by using the character as 
the least significant byte of a word quantity, with zero as the 
most significant byte. In other words, 'A' would become 0041 
hex. When two characters are used, the first becomes the MSB, 
and the second, the L S B : ' A B ' becomes 4142 hex. 


A number may be expressed in several different bases, as 
shown in the table below. A radix character immediately 
following the number indicates which number system is being used: 


Base 


Radix 


Valid Digits Valid Range 


hex H 

decimal 

octal 0 

binary 3 


0-9 , A-F 
0-9 
0-7 

0 and 1 


0 - 0FFFF 
0 - 65535 
0 - 177777 
16 digits 


If the trailing radix character is omitted, "H" (hex) is 
assumed. All numbers must begin with a numeric digit (0-9). A 
preceding minus sign indicates a negative number. In this case, 
a two's complement representation is used. 


The following are examples of 16-bit values: 

14170 - an octal number 

0C1B5 - a hex number 

-55. - a negative decimal number 

'A' - a one character literal 

1 1 B - 11 binary 

1 1 B H - 1 1 B h e x 



Module Linkage Editor 


Plink-II : PSA Object 

P 1 1 n k - 1 1 Input Format 



The following are not valid 16-bit values: 

100000. - decimal number too large 

960 - invalid octal digit 

' A B - missing closing quote 

C1C2 - does not begin with a digit 

3 . 3 L o c a 1 Variables 

Plink-II offers 50 variables that can store 16-bit values 
during the linkage edit, and may be used wherever a 1 6 - b i t value 
is needed. These are referenced as "tin", where n is a value in 
the range I - 50. For instance , " ft 1 " is a reference to the fir s t 
local variable. 

Mote that any 1 6 - c i t value will d c for n . In particular, 
another local variable may be used. For instance, if #1 equals 2 
and if 2 equals 10, the value of if it 1 is 10. 

To assign a value to a local variable, enter it n : = <value>, 
as s h o w r. b e 1 o w : 

it 1 : = 10 

It 2 : = 5 + 5 


Local Variables become useful when the command file requests 
input from the operator during the linkage edit (see section 8 ) . 

3 . K x p r e s s i o n s 

P 1 i n k - 1 1 supports simple, unparenthesized expressions of the 
form: <16 — b i t v a 1 u e > < o p > < 1 6 - b i t v a 1 u e > . The following 

operations are offered: 


* 

/ 

\ 

& 

! 


addition 

subtraction 

multiplication 

integer division 

remainder after division 

1 6 bit logical and 

1 6 bit logical or 


The minus sign may also be used as a unary minus (negative). 
Here are some examples: 


1 + 1 

-0C 1 5H 

II 6 * 10 (contents of local 5 times 10H) 

ill & 0 0 0 1 1 0 0 0 B (mask contents of local 1) 
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3.5 Identifiers 

An identifier is the name of some object, such as a module 
or segment. A simple identifier is a sequence of no more than 
eight characters containing no spaces, and containing none of the 
following: 

\ !’ //&» + -:§ DEL 

Note that an identifier for the data segment of a module (as 
discussed in the previous section) is preceded by a double quote 
( " ) , and can therefore reach nine characters in length. Lower 
case letters, when used, are automatically translated into upper 
case. The first character of an identifier may not be a digit 0 
- 9. 

A concatenated identifier may be created by following the 
character string by a " ~ " character, and then entering a local 
variable designation. The value in the local variable is 
converted to an ascii string in decimal (base 10) notation, with 
leading zeros truncated, and is appended to the end of the 
identifier string. For instance, if #3 contains the value ten, 
"LABEL''// 3 " would be treated the same as " L A B E L 1 0 " . The total 
length of the generated label must be eight characters or less. 

The following are examples of valid identifiers: 

Prog rami 
S0RT3 

"SORTS (a data segment name) 

F00$$$ 

BRANCH''# 1 (valid only if //I = < 99) 

The following are not valid identifiers: 

3^ ABC - begins with a number 

CHECKER SI - too many characters 
N 1 M A - contains a space 

PEOG-1 - contains an illegal character 

3 . 6 D isk File Names 

PI ink II adapts itself to the file name format used by the 
operating system it is executing under. However, it assumes that 
the characters 

~? = _; <>/ , DEL 

do not appear in file names. In this manual, CP/M format file 
names are used for purposes of discussion. These file names are 
of the form [device :]n am e[ .type] , with optional portions in 
brackets. Here are some examples: 


PROG 1 .COM 
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B : CHESS . PRO- 
SCAN NER 

When the "device:" is not used, Plink-II assumes that the 
currently logged- in disk is to be used. However, in the case of 
input files, Plink-II will look for a file on drive A if the file 
is not found on the logged-in drive. When the PDOS operating 
system is used, Plink-II will also look in user #5, drive A, in 
an effort to find the file. 

3.7 Initiating Plink-II 

Plink-II may be used interactively, or input may be given as 
it is executed: 

Plxnk-II < statement s > <cr> 

where <er> means to press the RETURN key. This means that 
Plink-II may used in submit files. 

To use Plink-II in the interactive mode, enter 

Plink-II <cr> 

on the console. Plink-II will read commands from the console, 
pro m pting with an asterisk All input is stored uninspected 

until a carriage return is typed. The standard line editing 
features (rubout, backspace, CTRL-U, CTRL-C, CTRL-E, etc.) 
supplied by the operating system are available. 

A d i. 3 k file containing all or only part of a command may be 
inserted into the input at any point by preceding the disk file 
name with an " § " , The default file type is " . L N K " . These d i s k 
files may not contain further " 9 . " specifications. The most 
common use of this feature is to prepare a file containing a 
complete command; then, 

Plink-II @<file name> <cr> 

links the program. Usually, these " . LNK" files may be prepared 
once for a given program and used over and over again, greatly 
simplifying the whole process. 

Plink-II reads an entire command, checking for syntax only, 
before any file processing is done. Then, the program is created 
before the next command is read. 
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3.8 Command Format 

All Plink-II commands have the same format, regardless of 
whether the interactive mode is used. Commands are separated by 
a semi-colon Plink-II terminates when it receives the "Q" 

command (quit). For example, 

<command> ; <command> ; <command> ; Q 

Plink-II also terminates when input provided with its 
execution is exhausted. 

All input is free format. Blank lines are ignored, and a 
command may extend to any number of lines. Comments may be 
included with input from any source by using a percent sign " % " . 
When this is encountered, all remaining characters on the same 
line are ignored. 

If a CTRL-C is typed while Plink-II is running, it will quit 
and return to the operating system. If CTRL-E is typed, the 
current command is aborted, and Plink-II will prompt for more 
input if it is being used interactively. 

Each command to Plink-II links one program, and is a list 
of statements: 

<statement> < s t a t e m e n t > ... <statement> 

The statements that make up a command typically begin with a 
key word, and many are followed by arguments separated by commas. 
Fo r example, in 

FILE A , B , C 

FILE is the key word, and A, B, and C are the arguments. 
Key words may be abbreviated by omitting trailing characters, as 
long as the abbreviation is unique among the entire group of key 
words. For instance, the previous statement could have been 
entered as 


FI A.B.C 

but it could not be entered as 

F A.B.C 

since this abbreviation could be confused with the FREEMEMORY 
command . 

If the program is linked successfully, its name is printed 
on the console, along with the address of the highest byte in 
memory used in the program and the program memory size rounded up 
to the nearest K (IK = 1024 bytes). 
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If a syntax error is found, the current input line is echoed 
with two question marks inserted after the point at which the 
error was detected. This is followed by an error message (see 
Appendix). The command must then be re-entered. 

If some other error occurs, the linkage edit terminates with 
an error message also listed in the appendix. 
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4 General Purpose Statements 
4 . 1 0 U T P U T 

The OUTPUT statement gives the name of the file that will be 
created to hold the linked program. The file type, if given, 
indicates what kind of file is to be produced. It must be one of 
the following: 


PRG - PSA code file, possibly containing overlays. These 
may be executed directly under PSA's operating 
system PDOS. A utility program (EXECUTE) is 
provided to execute them under other operating 
systems (see appendix). 


COM - Absolute binary cor - e-image file, ready to be loaded 
and executed by the operating system. 

If the file type is not given, it defaults to PRG if 
Plink-II is running under the PSA operating system and to COM for 
others. If the OUTPUT statement is not used at all, the name of 
the first input file specified is used, with a default file type. 
An error will occur if the selected file type does not agree with 
other statements in the command (for example, overlays in a .COM 
output file). 


The output, file replaces any existing file of the same name. 


Examples : 

OUTPUT PROG 1 
OUTPUT PROG2.COM 


4.2 PROG ID 

This statement may be used to set the program ID, version 
number, and revision number of a .PRG output file header (see 
appendix). The format is: 

P R 0 G I D <name> [,<version> [ ,<revision>] ] 

with optional input indicated by brackets []. The <name> is a 6 
character identifier, and the <version> and <revision> are values 
lying in the range 0 - 255. The <name> defaults to blanks, and 
the version and revision numbers default to zero. 

Examples : 


PROGID CHESS ,2,1 
PROGID TEST! 
PROGID PROG 5 , 10 
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4.3 P DOS 

This statement has an effect only when a . PRG file is being 
created. It sets the minimum version and revision of the 
operating system (PDOS) that must be used to execute the program. 
Its syntax is: 

PDOS <version> [,<revision>] 

The version and revision values must lie in the range 0-255, and 
the revision number defaults to zero if not entered. If the PDOS 
statement is not used, zero is assumed for both values, meaning 
that the program will run under any PDOS operating system. Trie 
purpose of the statement is to prevent programs from being 
executed which rely on new operating system features. 

Examples : 

PDOS 2 
PDOS 1,9 


4.4 MAP 


The MAP statement may be used to obtain various reports 
which describe the output of the linkage edit. Reports can be 
selected that show the memory addresses assigned by Plink-II to 
the sections, segments and symbols in the linked program, or that 
describe the modules that were included. 

The format of the MAP statement is: 

MAP < f 1 a g 1 > , < f 1 a g 2> ... , < f 1 a g n> 

The < f 1 a g > s select the desired reports, as follows: 

G - Global symbols (i.e. all internal symbols of all loaded 
modules). The symbols are listed in alphabetical 
order, with their assigned addresses. 

S - Segments. All of the program segments are listed in 
alphabetical order, and the assigned address and size 
is given for each. 

A - All. This option lists the entire output program, 
organized into sections. The sections are listed in 
address order, except where overlays make this 
impossible. The segments of each section, and the 
symbols in each segment, are listed in order of 
ascending memory address. Symbols created via the 
DEFINE statement or automatically supplied by Plink-II 
are listed separately. 
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M - Modules. Each module is listed, along with its ID 
number, version and revision number, and date and time 
assembled. This information is available only for PSA 
format modules. It is supplied by the .PROGID pseudo 
op in the PSA assembler. 

If no <flag>s are given, "MAP A" is assumed. Examples: 

MAP M , S , G 

MAP 

MAP S 


4.5 PAGE 


This 

statement 

may 

be used 

to set 

the page ’ 

w i d t h 

of the 

memory map 

reports. 

For 

example. 









PAGE 132 





sets the 

page width to 132 characters 

The 

various 

report 

generators 

make use 

of 

available 

page 

width 

by 

changing the 

number of 

columns per line. 






4.6 DATE 









P 1 i n k 

-II uses 

the 

current 

calendar 

date 

i n 

map 

report 

headings and to tag 

.PRG output 

file headers 

with 

the 

creation 

date. If 

the operat 

ing 

system is 

able to 

supply 

the 

date 

, and it 


looks reasonable, Plink-II will use it. If it is not reasonable, 
the operator is asked to enter - it (it must be entered character 
for character as shown in the prompt message). 

If the operating system can't supply the date, blanks are 
used unless the DATE statement appears in the input. The 
operator will then be prompted to enter it as described above. 
The DATE statement has no arguments: 

DATE 

4.7 REPORT 

Normally, ail memory map reports are written to the list 
device. This statement can be used to have them written to a 
disk file instead. A file name may be specified if desired, 
PRECEDED BY AN EQUAL SIGN. Otherwise, a file is created having 
the same name as the output program but with a type of .MAP. 

Examples : 

REPORT 

REPORT=BUDGET , LST 
REPORT = EXPENSE 
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4.8 MAIN 

Plink-II requires that a starting address for the progra m b e 
d e f 1 n e d . T 1; e starting address is part of the file he a der in a 
. PRG file ; see appendix), and PDOS transfers control to that 
address after loading the program into memory. Execution of a 
.COM file is assumed to begin at address 100H, so Plink-II places 
a jump at this location to the true starting address of the 
p f o g r a m . 

The starting address is always represented by a symbol named 
".MAIN.". If this symbol appears in the program modules, that 
one will be used. Otherwise, Plink-II will create it, and obtain 
a starting address from the first input module that has one. The 
MAIN s t a t c m ent may be used to override this default action a n d 
specify which module is the mai n m o d u 1 e o f t he program. Plink-II 
will then lock only at this module in order- to find a starting 
address . 

E x amp 1 e : 

MAIN PROG 1 

If t h e M A I N m o d u 1 e does not have a starting a d d r e s s Plink-II 
a s s u mes that it is at the front of th e m odule . 

A starting address is defined in the PSA A s s e m b 1 er by 
supplying a label with the ".END" pseudo op. Most compilers 
specify a starting address for the main module automatically, so 
this statement usually need not be used (for exceptions, see 
" M i c r o S o f t H i n t s " appendix). The starting address may be in an 
overlay if desired. 

4 . 9 D E F I i'l E 

T h i s option may be used to give values to symbol s w h i c h are 
n o t d e f i ned by any module in the program. T h ese d e fined s y m b o 1 s 
are then used to resolve EXTERNAL references made by the program 
modules. The symbols can be given absolute values, or may be 
defined as a plus or minus offset to some other s y m bol . F o r 
e x a rn pie: 

DEFINE CONST 1 = 1238. , FLAGS = 101 1001 IB, COUNT = it 5, 

SI = 1 0 , S2 = SI , S3 = S2 + 5 

Note that when a symbol is defined as an offset to another, 
the expression following the plus or minus sign is evaluated 
separately. For instance, 

DEFINE A = B - 2 + 3 

is e q uivalent to 

DEFINE A = B - 5 
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There are some symbols which are pre-defined by Plink-II. A 
list of them is given in Appendix A. 

4.10 CONCATENATE 

As discussed in the overview, module segments other than the 
program and data segments are treated as common blocks, so that 
each module shares the same memory space. The CONCATENATE 
statement changes a common block into a "concatenated segment". 
In these, each module is allocated its own memory space and no 
sharing takes place. However, the space used by all modules is 
concatenated together (in the order encountered) to form a single;* 
segment. This statement is useful for tasks such as constructing 
a table where each module contributes one table entry. 

The segments to be concatenated are listed, separated by 
commas : 


CONCATENATE COMMON 1 , C0MM0N2 
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5 Defining Program Structure 

In this section the statements that cause particular files 
and modules to be linked into the program and define the memory 
structure of the program are described. As discussed in the 
overview, Plink-II groups program segments having similar 
characteristics into SECTIONS. In other words, segments are 
loaded into the same section until something like a change of 
memory address or an instruction to start an overlay area is 
encountered. Then, a new section is begun. 

5.1 FILE, LIBRARY, SEARCH 

These statements are used to define the . REL files and 
librarys that will be the input to the linkage edit. Each of 
them is followed by a list of .REL file names, separated by 
commas : 

FILE MAIN, PASS!. REL, PASS2 

SEARCH PASLIB 

LIBRARY MATH. LIB, APPLIB 

The default file type for these files is .REL. All of the 
modules contained in files listed in the FILE statement are 
included in the output program (except for those specifically 
eliminated by a following statement). When the LIBRARY statement 
is used, only those modules defining symbols that were used by 
modules already linked, but not defined yet, are selected. This 
selection process j. s known as a "library search", and is commonly 
used for the runtime support librarys supplied with most 
compilers: the size of the program is reduced, because only 

those parts of the runtime support that are actually needed are 
loaded. 


The SEARCH statement is the same as LIBRARY except t h a i 
Flink-II may make multiple passes through the file if undefined 
symbols remain even after all specified files have been read. 
This capability is provided because sometimes a library module 
has undefined symbols that are defined only by modules that have 
already been passed over. It should hardly ever be necessary to 
use it: most librarys are set up to be loaded with a single pass. 

The modules encountered in files loaded with the FILE, 
LIBRARY, and SEARCH statements are normally assignee to the 
current section, but other statements (described later) can 
override tnis default action. 


5.2 I N CLUDE, EXCLUDE 


These statements apply to the file last 
LIBRARY, or SEARCH statement, and are used 
more modules from the linkage edit. The 
separated by e o rn mas: 


mentioned in a FILE, 
to eliminate one or 
modules are listed, 
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INCLUDE M0D1.M0D2 
EXCLUDE MOD 3 

The EXCLUDE statement prevents the named modules from being 
included in the linkage edit. When the INCLUDE statement is 
used, all modules except the ones named are excluded. This 
action occurs prior to any library search selection. INCLUDE and 
EXCLUDE may not be used on the same file. 

5.3 MODULE, SEGMENT 

When the FILE, LIBRARY and SEARCH statements are used, all 
of the selected modules are usually loaded into the current 
section. These statement override this default action, and place 
given modules or segments into the current section. The module 
or segment names are listed, separated by commas: 

MODULE MAIN, M0D5 
SEGMENT MAIN, "MAIN, MODS 

The SEGMENT statement may be used on any segment. The 
MODULE statement should be used only on modules, and is the 
equivalent of a SEGMENT statement on the program and data (if 
any) segments of the module. For instance, in the above example 
the two statements have the same effect if M 0 D 5 has no data 
segment . 

5 . 1 S ECT10N 

The SECTION statement is used to give an 8 character name to 
the current section: 


SECTION global 

The name is used for memory map reports. If a name of 
.ROOT. is used however, this statement has the effect of 
specifiying the main section of the program. This is the section 
that will be loaded from the . PRG file when the program is 
executed. Any other sections are loaded by the overlay handler 
(see discussion of overlays following). 

5.5 NOSORT 

Normally, the segments within each section are sorted so 
that uninitialized ones are grouped at the end (an uninitialized 
segment is one that may reserve memory space, but has no code or 
data in it). Sorting a section this way minimizes the disk space 
required to store it, since no space is needed for the 
uninitialized segments at the end. Note that the program must be 
careful about initializing data in this case, because garbage is 
left in memory in the uninitialized places when the section is 
loaded. If this is a problem, or if the user requires for other 
reasons that the segments within a section be left in input 
order, the NOSORT statement m a y be used. It a p p 1 i. e s to t h e 
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current section only, and has no arguments. 

Aside from moving the uninitialized segments to the end, the 
sorter leaves the segments in the order encountered in the input 
files. However, the Fortran blank common . BLN K . is sorted last 
(if uninitialized). This is done to facilitate the access of 
Fortran programs to free memory. 

5.6 .DATA. 

Occasionally it is convenient to group together all data 
segments of a program into a single section, for example, to 
create a R 0 M a b 1 e program. The .DATA. statement, which has no 
arguments, is used for this purpose. When encountered, a 
separate section is created, and all data segments are assigned 
to it, unless the MODULE or SEGMENT statements are used on them. 
These statements override the FILE, LIBRARY and SEARCH 
s t atements . 

5 . 7 S C T E N D 

This statement rn a y be used to end the current section and 
cause a new one to be started. It has no arguments. 

5.3 LOCATE 

N o r rn a 1 1 y , PI i n k - I I assigns memory addresses sequentially to 
segments as they are encountered in the input files. This 
statement changes the address where subsequent memory allocation 
will occur, and begins a new section. The new address must be 
greater than or equal to the current allocation address. 

Example : 

FILE PROG 1 , PR0G2 
LOCATE 4000H 
MODULE MODI 

In this example, the modules in files PROG 1 and PR0G2 are 
loaded at the beginning of available memory, but module MODI is 
loaded at address 4000H , even if it is contained in PR0G1 or 
PROG 2 . 

Another handy use for the LOCATE statement is the creation 
of a "patch area" within a program: 

OUT PROG.COM 
LOCATE 200 

FILE PROG 1 , PR0G2 , PROG2 

This program has a "hole" starting at address 10?H and 
extending up to address 2 0 0 H , which could be used for patches 
(see appendix for .COM file format). 
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When a COM file is being output, "holes" created with the 
LOCATE statement appear in the disk file as well as in memory; a 
COM disk file is always an exact image of what the program will 
be when loaded into memory. When a PRG file is created, however, 
the hole is not present in the disk file. Only the space needed 
by each section is allocated, and when the program is executed, 
only the "global" section is loaded into memory by the o per at i tig 
system; any other sections are automatically loaded by 

initialization code generated by Plink-II, using the overlay 
handler (see discussion of overlays following). The global 
section is the usually the first non -overlaid section, or may be 
specified by using the SECTION statement. 

5 . 9 A C T U A L 

As discussed in section 2, each program segment is normally 
relocated to execute at the memory address at which it is to be 
loaded. When this statement is used, however - , a new section is 
begun, and all segments within it will be assigned execution 
addresses starting at the given value. This includes changing 
the value of all addresses referenced from inside or outside 
those segments (presumably, the segments will be moved at run 
time to the correct execution address). The ACTUAL applies only 
to the new section (for instance, it can be turned off via a 
5 C T E N D statement) 

F o r e x a m pie, suppose it is necessary to create a program whic h 
will run on a non-CP/ M type system which loads programs at 
address 4 0 0 0 H : 

OUT PROG.COM 
ACTUAL 4 00 OH 
FILE PROG .REL 

Here, a .COM file is created having the code for PROG. REL at 
the front, but the addresses within the code are adjusted to 
execute at 4Q00H. This feature is also ideal for tasks such as 
the creation of bootstrap routines and 1/0 drivers which have to 
be moved to non-standard addresses before use. 

5.10 FREEMEMOR Y 

Often, a program requires the address of any free memory 
left over after the program is loaded (for example, the PASCAL 
heap). Plink-II will use the first byte following the program 
for the free memory address by default, but this statement may be 
used to put the free memory at the current allocation address 
instead. For example, 

FILE MAIN, MODI, M0D2, M0D3 

FREEMEM0RY 
FILE 


I N I T 
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Here, the space used by the initialization code in file IN IT 
is re-used as free memory when the main program begins execution. 
FREEMEMOR Y begins a new section, which in this case starts with 
I N I T . 

Plink-II creates a symbol named ".END." which has as its 
value the free memory address. Also, the words at symbols $ M E M R Y 
and ? M E M R Y are initialized to this value (if the symbols exist) 
for Microsoft and Digital Research PL/1 programs. 

5,11 Creating Overlays 

If a program is too large to fit into memory, OVERLAYS must 
be used. Overlays are simply sections of the program which are 
set up to use the same memory area. When overlays are specified, 
an overlay loader module is automatically included into the 
program. The loader reads the overlays from disk into memory 
a u tomatically as required by the executing program. Since 
portions of the program share the same memory space as the 
program runs, the memory r e q u i r m e ri t of the program is reduced. 
The disadvantage, of course, is that the program runs more slowly 
due to the extra time needed to lead the overlays from disk. 

These statements are used to define overlay structures. 
Normally, arbitrarily complex overlay structures may be created 
with no m odifications to the program modules, but some rules 
concerning calling sequences and accessing data must be obeyed. 
Also, the overlay structure should be organized to minimize the 
number of times overlays have to be loaded in: if a program loop 

that is executed 100,000 times lias to switch from one overlay to 
another each time, and it takes .05 seconds to load an overlay, 
the program will run for almost three hours! Some of these 
issues will be discussed more fully later on. 

An OVERLAY AREA is a group of overlays which share the same 
memory address. To create an overlay area beginning at the 
current memory allocation address, the BEGINAREA statement is 
used (no arguments). Each overlay area must be ended by an 
ENDAREA statement. Each overlay within the overlay area is begu n 
by an OVERLAY statement. This is followed by FILE, LIBRARY, 
SEARCH, MODULE, or SEGMENT statements to place the desired items 
into the overlay. 

Here is a simple example: 

OUTPUT TEST. P R G 

FILE FI 

BEGIN OVERLAY FILE F2 
OVERLAY FILE F3 
OVERLAY FILE F4 END 
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This command creates a program named TEST.PRG. When it is 
loaded by the operating system (or the EXECUTE utility if a 
non-PDOS operating system is being used) only the code in file FI 
is loaded: this is referred to as the RESIDENT section of the 
program. Then execution begins. Suppose a call i 3 made to some 
code from file F2. The overlay loader is automatically invoked 
to read that overlay from the . P R G file, and then a branch is 
made to the called routine. Later, if a call is made to code in 
F 3 , for example, F 3 will be loaded, over-writing F2 . If F 2 is 
called again before F3 or F 4 , however, no disk I/O need be done 
since the required overlay is still in memory. Note that 
overlays are not stored back on disk when they are over-written, 
and a fresh copy is loaded the next time the overlay is needed: 
the PRG file is never modified. 

Plink-II accomplishes these tasks by replacing an address 
pointing to an overlaid routine with a call to a small piece of 
code which calls the overlay loader, to insure that the proper 
overlay is in memory, and then jumps to the overlaid routine. 
I his piece of code is called an OVERLAY VECTOR. Note that a 
program can either call, or jump to an overlaid routine. However, 
the user must insure that when a return to the caller is made, 
that the caller is still in memory. In the previous example, for 
instance, if F2 calls F3, F2 will be smashed by F3 before the 
return to F2 is made, resulting in a program bug. F2 could j u m p 
to r 3 with no problem, however. 

Note that P 1 i n k has no way o f knowing whether an address in 
an overlay represents code or data. In this example, for 
instance, if F2 references F 3 , it is always assumed to be a call 
or jump: data can't be accessed from one overlay to another in 
the same area. A more exact rule for how data may be access el 
within overlays will be given shortly. 

In order tc more easily discuss overlay structures, Memory 
Diagrams such as figure 1 will be used. In these diagrams, the 
vertical dimension represents memory addresses, with lower 
addresses at the bottom. The horizontal dimension is used t > 
indicate where memory locations are shared. In figure 1, for 
instance, FI reaches all the way from left to right because it 
shares its memory with no one: it is resident. F 2 , F 3 , and F 4 
share the same memory space within the overlay area. Since F 3 is 
larger than F2 or F 4 , some memory is unused when these overlays 
are in memory. These wasted areas are shaded in. 
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Figure 1 

More than one overlay area may be created. Any additional 
ones are allocated to the next available space in memory, as in 
trie following command: 

OUTPUT TE3T2 

FILE FI, F 2 , F3, F4, F5, F 6 , F7 
BEGIN OVERLAY SEG MODI 

OVERLAY SEG M0D2A , M0D28, M0D2C 
OVERLAY SEG M0D3 END 
BEGIN OVERLAY MOD MOD4 
OVERLAY SEG MODS 
OVERLAY SEG M0D6 END 

Here two independant overlay areas are created. One overlay 
from the first and one from the second may be in memory 
simultaneously, as shown in Figure 2. Another feature of thin 
command should be noted. All of the input files are simpl/ 
listed in the beginning, and the desired segments to be overlai 1 
are pulled out via the SEGment or MODule commands. Therefore, 
most of the data segments and common blocks will be allocated t> 
the resident section. This is usually desirable, as any data i i 
an overlay may be smashed when another overlay overlapping it in 
memory is read in. Another way of accomplishing this task is b / 
using the .DATA. statement outside of the overlay areas: thin 

will automatically pull all of the data segments and common 
blocks out of the overlays. If it is desired to have a data 
segment assigned to the same overlay as its related program 
segement, the MODULE statement could be used instead of SEGMENT, 
as shown for M 0 D 4 . 
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Figure 2 

Notice that in Figure 2, the second overlay area starts in 
memory after the largest overlay in the first area. The SHARE 
statement can be used to cause Plink-II to ignore the following 
item when calculating the maximum size of an overlay area. 
Suppose, in the example of Figure 2, that Mods 4 - 6 will never 
be accessed when Mods 2a - 2c are in memory. Then the program 
could be made slightly smaller as follows: 

OUTPUT TEST2A 

FILE FI, F2 , F3, F4, F5, F6, F7 
BEGIN OVERLAY SEG MODI 

SHARE OVERLAY SEG M0D2A , M0D2B , M0D2C 
OVERLAY SEG M0D3 END 
BEGIN OVERLAY MOD M0D4 
OVERLAY SEG M0D5 
OVERLAY SEG M0D6 END 

The resulting memory organization would be as shown in 
Figure 2A. When the Mod 2 a - c overlay is in memory, none of the 
others may be. When Modi or Mod 3 are in memory, one of Mods 4 - 
6 may be in memory simultaneously. 
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Figure 2a 

Another mechanism for creating overlay structures result:; 
from the fact that the BEGIN' AREA and ENDAREA statements may be 
nested to create overlay structures up to 32 levels deep, as 
shown in the following example: 

OUTPUT TEST 3 

BEGIN OVERLAY SEG MODI 

OVERLAY SEG M0D2 BEGIN OVERLAY SEG M0D4 

OVERLAY SEG M0D5 
OVERLAY SEG M0D6 END 

OVERLAY SEG M0D3 END 
FILE FI , F 2 , F 3 , F4, F5 , F6, FT 

In order to discuss this overlay structure (see figure 3), 
some new terminology must be developed. Every section of a 
program is assigned a LEVEL NUMBER. Resident sections an 
assigned a level number of zero. Whenever a BEGIN AREA command i: 
entered, the level number is increased by one, and it i: 

decreased by one at an ENDAREA statement. In Figure 1, FI is- 
le v e 1 zero, while F2, F3 and F 4 are level 1. In Figure 3 * MODs 
thru 3 are level one, and MODs 4 thru 5 are at level 2. 

Every overlaid section has an ANCESTOR. An overlay’: 
ancestor is the last section defined prior to the beginning oi 
the overlay area and at a lower level number. In figure 1, FI is 
the ancestor of F 2 , F3 and F4. In figure 2, the global section 

is the ancestor of all the over- lays. In figure 3, the globa 

section is the ancestor of MODs 1 thru 2,3 while M0D2 is t h < 
ancestor of MODs 4 thru 6 

The ANCESTORS of an overlay consist of the overlay’ : 

ancestor, the ancestor of that overlay, and so on, until 
resident section is reached. Notice that the number of ancestor: 
an overlay has is equal to its level number. For instance, ii 
figure 3, the ancestors of M0D5, which is at level 2, are MODI 
and the resident section. 
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Conversely, a section's DESCENDANTS consist of all those 
sections which have it as an ancestor. The descendants of M0D2 
are M0D3 4 thru 6. 
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Figure 3 

Now the rule for accessing data within overlays can bo 
explicitly stated: data within an overlay may be accessed only 

from within the overlay, or from one of the overlay's 
descendants. For instance, data within M0D2 may be accessed only 

from within M0D2 or from MODs 4 thru 6. The data within MODI may 
be accessed only within MODI, since it has no descendants. 

Plink-II works with the overlay loader to guarantee the* 
"data access rule" by obeying the following rules: 

1. Whenever an overlay is in memory, all of its ancestors must 
be in memory as well. For instance, if in the example of 
Figure 3 M0D6 were to be called with no call to M0D2, M0D2 
would be automatically loaded anyway. 

2 . The overlay vectors are never used when an overlay accesses 
a descendant. This means that any instructions which 
access data in this direction are not modified. 

The SHARE statement may be used on an entire overlay area. 
In this case, the size of the overlay area is not included in the 
maximum size of the surrounding overlay area. 

5.12 Selecting an Overlay Loader 

Normally, the overlay loader must reside on disk in a file 
named OVERLAY. REL. It should not appear in a FILE, LIBRARY or 
SEARCH statement. 

Three versions of the overlay loader are supplied on the 
Plink-II distribution disk. OVERLAY. REL is the standard loader, 
and requires a 280 (*) processor. 0VERLAY8.REL is a. loader which 
will run on an 8080 ( * ) processor. It may be selected by using 

the 18080 statement, which has no arguments. There is also an 
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OVERLAYD.REL file. It contains a debugging overlay loader which 
displays messages on the console indicating what overlaid 
addresses are being called, and which overlays are being loaded. 
The memory map A report will be helpful in interpreting these 
messages. This loader will also execute on an 8080 processor, 
and may be selected by using the DEBUG statement, with no 
arguments . 

For example, suppose you have a Plink-II command file 
PR0G1.LNK which links some program with overlays, and you wish to 
create a version of the program that uses the debugging overlay 
loader. Typing 

PLINK-II DEBUG §PR0G1 
would create the desired program. 


( * ) Z 8 0 is a trademark of Z i 1 o g . 

( * ) 8080 is a trademark of Intel Corp. 
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6 Transfer of Control 

Any Plink-II statement may be optionally preceded by a 
LABEL, which is simply an identifier followed by a colon: 

LI: FILE PROG 1 

These labels may be used as branch points with some simple 
statements described here. 

The GOTO statement causes an unconditional branch to the 
given label: 


GOTO LI 

When this statement is used, Plink-II searches forward 
through the input stream (wherever it is coming from, see section 
3) to find the label. If the end of the input is reached without 
finding it, the input stream is reset to the front, and the 
search begins again. If input is coming from the console, it is 
reset to the beginning of the current line only: transfer of 
control statements are generally useful only when input is coming 
from a disk file. 

Since this search process is rather slow, the BACKTO 
statement is supplied. It is the same as GOTO, but resets the 
input stream to the front immediately before beginning tie- 
search . It is therefore faster when the label precedes the goto 
statement . 

Either GOTO or BACKTO may be preceded by an IF statement to 
create a conditional branch. The IF is followed by a simple 
relational test, as in the following example: 

IF #1 = ' Y * BACKTO L2 

The relational test consists of two 16-bit values separated 
by one or two relational operators from the set = , <, and >, 
which mean "equals", "less than" and "greater than", 
respectively. For example, to test for "not equal" one would use 
" < > " . 


The transfer of control statements become useful when the 
input stream performs alternative actions based upon operator 
input, as described in the next section. 
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This section describes statements that can display messages 
and get input from the console. When these statements are used 
in an file, in conjunction with the transfer of control 

statements given in the previous section, Plink-II can be used as 
a program configuration system that generates different versions 
of the program based on operator input. 

The DISPLAY statement takes as arguments items to be 
displayed on the console. The following items may be displayed: 

literal - the literal is displayed as is, without the 

surrounding quotes. 

TAB - a tab character is output. 

C R - a carriage return/linefeed sequence is output. 

BELL - a Q7H is output. 

1 6 - b i t value - The value is displayed in the current radix. 

HEX - this does not cause any display to take place, 

but changes the radix that all following 16- bit 
values are printed in to hexidecimal. This is 
the default at the start of the DISPLAY 
statement. 

DECIMAL - this displays nothing, but changes the 16- bit 

value display radix to decimal. Leading zeroes 
are truncated. 

Here is an example of DISPLAY usage: 

DISPLAY BELL, 'Linkage edit completed', CR 

There are three commands for getting values from the 
operator. They all require a local variable as the first 
argument, which is where the value will be stored, and optionally 
take a CR as the second argument. When used, this will cause a 
carriage-return line-feed to be echoed following the operator's 
input . 

The G E T V A L statement inputs a 16-bit value in any of the 
allowed forms . PROMPT inputs a single character, converts it to 
upper case, and interprets that as a 16-bit value. GETCHR is the 
same, but requires the operator to hit the return key after the 
single character has been entered. This gives the operator a 
chance to inspect the character and/or correct it. 
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Here is an example of how the input/ output statements might 
be used. Suppose we have a program that uses some special 
purpose data communications hardware that comes in two 
variations. Three modules are written which have the same ENTRY 
symbols but different code to support the two versions of the 
hardware, and a third module for testing purposes. A single 
command can link all three versions of the program, asking the 
operator which version of the data communications driver is 
wanted : 


ASK : 

DISPLAY BELL, 'Enter 0 for ACME 510 Modem 1 , 

1 1 for ABC Electronics Modem' , CR 

*2 for self-test loop = >' 

GET VAL #1, CR 
IF #1=0 GOTO ACME510 
IF #1=1 GOTO ABC 
IF #1=2 GOTO SELF 
BACKTO ASK 

ACME510: FILE ACME510 
GOTO END 

ABC: FILE ABC 

GOTO END 

SELF: FILE SELFLOOP 

END : 


The correct file is linked depending on the operator':; 
selection. This particular problem could have been handled by 
having three separate link command files, but what if a system 
has 10 versions of one module, and 10 of a second module? Then 
100 versions of the program are possible, and the interactive 
methods offered here are clearly advantageous. 


Another way to handle the above example is to use the 
"concatenated ID" mechanism described earlier to create a label 
to GOTO by appending the operator's response to a label prefix. 
Also, the three modules to be selected from are combined here 
into a library, and the INCLUDE statement is used to select the 
correct one. 


FILE DRIVERS. LIB 
GET VAL #1,CR 
IF #1>2 BACKTO ASK 
GOTO LAB - '# 1 

LABO: INC ACME 1 0 GOTO END 

LABI: INC ABC GOTO END 

LAB2 : INC SELF LOOP 

END: 
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Appendix A - Pre-Defined Symbols 

There are a few global symbols which are pre-defined by 
Plink-II before the linkage edit begins. They are listed below. 
The user should not attempt to define these symbols, as naming 
conflicts will result (except in the case of .MAIN.). Future 
versions of Plink-II may have more of these symbols. They will 
be of the form . X X X X , , so the use of symbols of this form should 
be avoided. 

.END. - This symbol has as its value the address of free memory. 

Normally, this will be the address of the first byte 
above the program, but this default action may be 
changed via the FREEMEMQRY statement. 

.MAIN. - This symbol may be defined by the user, or will be 
defined by Plink-II otherwise. It has as its value the 
starting address of the program (see the MAIN 

statement) . 

. 0 V L l . - This is the entry point to the overlay loader used by 

the overlaid symbol vectors. 

.LOAD. - This is another overlay loader entry point which is used 
to load sections of code in .PRG files which are 

resident but not loaded by the operating system at 
execution time. It may also be used by the program to 
cause any overlay to be loaded. The A register must, 
contain the overlay number. These numbers are given in 
the memory map A report. 

.GVEX. - This symbol points to the last instruction in the 
overlay loader before control is transferred to t h ‘ 
overlay. It is useful for debugging (breakpoints can't 
be set in an overlay until it is present in memory). 

.INIT. - This symooi points to the initialization code for , i 
program containing overlays. In such programs, control 
is passed to the overlay loader's initialization routine 
after the program is loaded. When the overlay loader in, 
finished initializing itself, it jumps to this label. 
The linkage editor generates code here to load resident 
sections of the program not loaded by the operating, 
system (using the .LOAD. entry point in the over la; 
loader) and then jumps to .MAIN., the true starting, 
address of the program. 

In addition to the above pre-defined symbols, if a Microsoft 
format RF.L file was included as part of the input, and hat 
defined a global symbol named " $ M E M R Y " , then the value of .END. 
is stored at that address. The ? M EM R Y symbol is handled the same 
way for Digital Research PL/I programs. 
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COM File Format 

COM files are the standard executable file accepted by CP/M 
type operating systems. They are designed to be loaded into 
memory at address 100H. Therefore, disk addresses equal memory 
addresses minus 1 OOH . Plink-II places a 7 byte initialization 
routine at address 100H which loads a pointer to free memory into 
the stack register and then jumps to the start of the program: 

LHLD 6 

S PH L 

JMP .MAIN. 

If the initialization routine is not wanted, a "LOCATE 100" 
statement may be used to start the program at 100H, overwriting 
it. Hopefully, the first executable instructions of the program 
would be at the very front. 

.PRG File Format 


PRG files are output files that can be executed directly 
only on Phoenix Software Associate's PDOS operating system. A 
utility program is supplied to execute these programs under CP/M 
type operating systems (see appendix). A PRG file must be 
created if overlays are used. 

PRG files have a 128 byte header in front which has the 
following format: 


Address Size 
(hex) (bytes) 
0 6 

6 3 

9 3 

C 2 


E 2 

1 0 2 

1 2 2 

1 4 2 

1 6 2 

1 8 2 

1 A 2 

1C 100 


PRG file header 
Contents 

Program ID 

Date linked (packed BCD) 

Time " " 

Minimum PDOS version and revision 
required for execution 
Program version and revision 
Required program memory space 
Memory load address 
Program starting address 
Program load size 
Requested stack address 
Address of overlay table 
Reserved for future expansion 


When the program is to be executed, the minimum PDOS version 
and revision number are checked against their current values. 
Loading continues only if the current version is greater than or 
equal to the version number given in the header. In this way, 
programs using new PDOS features are protected against execution 
under operating systems not having these features. 
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Next, the total amount of memory needed to run the program 
is checked against the amount actually available. The execution 
is aborted if not enough memory is available. This check 
prevents programs from being executed which might fit into memory 
initially, but will smash the operating system when overlays are 
done. 


If the program passes these tests, it is loaded from disk 
(beginning after the header) into memory (at the specified memory 
load address). Only the amount of the program given in the load 
size field is loaded: the rest of the .PRG file, if any, consists 
of overlays. 

When loading is complete, the stack register SP is set to 
the value given in the PRG header. If this value is minus 1, 
however (FFFFH), SP is loaded from address 6, which contains the 
highest address available to the program (recall that the Z80 
stack grows down in memory). Finally, control is transferred to 
the given starting address. 

Most of the other information in the PRG header may be 
printed by using the PDOS VERSION command. 
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Appendix C - More Plink-II Examples 

Here, some examples that illustrate a few points not brought 
up fully in the body of this guide are presented. 

Example 1 

Suppose you have a program consisting of just one module, 
contained in file TEST. PEL. To produce a file TEST.COM to 
execute, just type: 


Plink-II FI TEST<cr> 


Recall that the name of 
of the first input file (the 
is a simple link, with no 
module must have a defined 
symbols . 


the output file defaults to the name 
only input file in this case). This 
memory map or other options. The 
starting address, and no external 


Example 2 


Suppose a program has been created consisting of three 
modules: MODI, M0D2, and M0D3. Each of these modules exists in 
separate disk files, called M0D1.REL, M0D2.REL and MCD3.REL. 
MODI is the module where execution is to begin, and it has a 
defined starting address. To create a COM file ready for 
execution, execute Plink-II, and in response to the prompt, enter 
the following command: 


OUT PROG.COM 
FI MODI, M 0 D 2 , M0D3 
MAP M A 
REPORT ; 


Two memory map reports will be written to disk file 
P R 0 G „ M A P . When Plink-II has finished, enter Q (followed by a 
carriage return) to terminate it. 

Ex ample 3 


Suppose that it is desired to add an I/O driver for a line 
printer to the system. The I/O driver is to be loaded high up in 
memory, so that it will not interfere with normal user programs. 
When executed as a normal program, the driver is to automatically 
load itself into the correct address and stay there until the 
computer is powered off. This is easily accomplished by using 
some of Plink-II' s special options. 
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The program will consist of two modules: the driver itself, 
and a loader module. Suppose that the printer is interfaced 
through a single port, number 90. An input from this port gives 
the printer status: a zero indicates that the printer is ready 
to accept another character, while anything else indicates that 
the printer is not ready (power off, out of paper, etc.). 
Characters are printed by writing them to port 90. The driver is 
used by calling it with a character to be printed in the A 


r eg i s t 

e r . T h e 

following 

Z80 assembler code makes up the driver 

module 

• 




. I D E N T 

DRIVER 



. ENTRY 

PRINT 


P R I NT : 

> 

MOV 

C , A 

; S A V E CHARACTER 

. . WT : 

IN 

9 OH 

; W A I T FOR READY 


CPI 

0 



J R N Z 

. . W T 



9 

M 0 V 

A , C 

; RESTORE CHARACTER 


OUT 

9 OH 

: OUTPUT IT 


RET 




.END 



A 

m o d u 1 e 

is p r oduced 

with a single entry point, PRINT. Now 


for the Plink-II input. The following Plink-II command is placed 
into a file called PRINTER. LNK: 

OUT PRINTER. PRG 
FILE LOADER 
LOC OF800 
FILE DRIVER 
M A P 


Finally, after assembling LOADER and DRIVER, typing: 

Plink-II SPRINTER 

causes the desired program, PRINTER. PRG, to be created. 

What happens when PRINTER is executed? Since there is a gap 
between the LOADER and DRIVER modules because of the LOCATE 
statement, Plink-II includes the overlay handler into the 
program. Only the LOADER module is loaded by the operating 
system: initialization code generated by Plink-II calls the 

overlay loader to load DRIVER. In other words, the LOADER module 
doesn't have to do anything but return to the operating system! 
All the rest is taken care of automatically. 

If at a later time it is desired to load the printer driver 
at a different address, this may be accomplished by simply 
changing the argument to the LOCATE statement. Neither of the 
modules would have to be r e- a s s emb 1 ed . 
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Appendix D - Microsoft, Hints 

As described earlier, Plink-II will accept Microsoft format 
R E L (relocatable) files as input to a linkage edit. The 
Microsoft format is rapidly becoming an industry standard for 7.80 
compiler output. However, several- manufacturers are selling 
compilers which output files that look like Microsoft’s, but 
actually contain subtle differences. Pi ink can handle some of 
these as is, and some can be handled if certain restrictions are 
maintained, but others will not work. Also, Microsoft, 

periodically makes minor changes to the format in order to 
support new language features. 

The list below indicates which compilers have been checked 
out with Plink-II. Usually, lower numbered versions are also 
handled correctly. If a compiler you wish to use is not on this 
list, either insure that it outputs a format compatible with a 
listed one, or contact Phoenix Software Associates. 

Microsoft : 

- C o b c 1 4.01: in 4,01, the SECTION statement may not be used. 

- Fortran 3.31: the blank common is automatically renamed to 
. BLN K . by Plink-II. 

Cromemco : 

- C o b o 1 3.01 

Digital Research 

- P L / 1 1.2: the indexed . I R L files are not supported: they will 

have to be converted to normal form with the LIB program. 

M T Microsystems: 

- Pascal MT+ 5.1: .ERL files designed to be input to the 

disassembler are not supported. Also, the MAIN statement must 
be used to indicate the main module of the program since these 
•PEL files do not specify the starting address. 

When using Microsoft format files, the following points 
shouid be remembereu: 

1 . When overlay structures are created, a common block may not 
s h are the same memory space with another common when both are 
accessed by the same module, or error #93 will result. This 
is due to the fact that fix up addresses are given in terms of 
memory addresses, addresses in overlapping commons are 
ambiguous . 

2. A runtime suppor y library is provided with most compilers, and 
it usually must be specified via the LIBRARY command (i.e. it 
is searched only once). However, some compilers use the 
automatic library search feature that is offered in the 
Microsoft format. In these cases the LIBRARY statement need 
not be used, although it will do no harm if entered. 
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Appendix E - PSA Assembler Hints 

This appendix is a list of hints which may be of help in 
setting up PSA Assembler modules for use with P 1 i n k - 1 1 . 


SYMBOLS 


Internal and External symbols are created by using the 
.INTERN and .EXTERN pseudo operations. .ENTRY is used to create 
e n t r y - p o i n t s ymbol s . 

SWITCHES 

When assembling a module for use with Plink-II, do not use 
the .PADS or .XL. INK switches. Do use the .PR EL and .LINK 
switches (these are defaults). You may use the . PHEX switch to 
get an ASCII . R E L file, but using . P B I N (the default) will result 
in a savings of disk space. 

MODULE NAME 

Always use the . I D E N I operation to give each module a unique 
n ame . If you don't, the modules will all have the name .MAIN., 
creating naming conflicts if Plink-II statements reference those 
m o d u I. e s or their program and data segments. 

. LOC Pseudo Op 

Do not attempt to load some code or data at an absolute 
address by using the .LOG pseudo op with a number. If you want 
to load something at an absolute memory address, make it a 
separate module or common block, and use t h e LOCATE statement of 
Plink-II to put it where you want it. Error it 50 will occur if an 
attempt is made to specify an absolute load address in a module. 

STARTING ADDRESS 

A label should be supplied with the .END pseudo op to define 
the starting address of the main module of the program. If any 
other modules to be linked also have a starting address, it is a 
good idea to use the MAIN statement of Plink-II to indicate the 
main module. 


Alternatively, make the starting address .MAIN., and declare 
.MAIN. as an .INTERN symbol. 

The starting address MAY NOT be an absolute symbol: it has to be 

relative to some m o d u 1 e . 
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LIBRARIES 


Libraries may be created by using the .PRGEND switch. This 
results in the creation of a new module starting at that point. 
Alternatively, individual R E L files may be concatenated into a 
single file by most file copy utility programs. One has to be 
careful, however, that CNTL-Z is used as an end of file condition 
for ASCII files, but physical end of file is used for BINARY 
files. Binary and ASCII modules may be mixed together in a 
library. Microsoft and PSA REL files may not be mixed in the 
same library. 

MEMORY MAP 


If the M report of the memory map is wanted, use the .PROGID 
pseudo op to define the program name, version number, and 
revision number. 

COMMON BLOCKS 


To make a common block, declare the common b 1 o c k name to be 
an .EXTERN in each module that must reference it. The common 
should not be declared .INTERN by any module. Then, use .LOG to 
define the common. For example, 

.EXTERN TABLE 



. LOC 

TABLE 

A : 

.WORD 

5 

3 ■ 

. BLKB 

1 C 

C : 

. ASCII 

"ABCDEFG" 


. RELOC 

declares a common named TABLE consisting of A, a word, B, 10 
bytes long, and C, an ASCII string. A useful way to handle 
commons referenced in several different modules is to keep the 
common definition in a separate file and use the .INSERT 
statement to include it with each module. 

Remember that most FORTRAN compilers will name a common 
.BLNK. if the programmer does not give it a name. 

DATA AREA 


Objects are placed into the data segment of a module by 
preceding them with a . LOC .DATA. The programmer may .LOC .DATA, 
over and ever again in the program: each definition is added on 
to the end of the previous ones. For example: 
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. LOC .DATA. 
F00: .WORD 0 

BAR: .BYTE 55H 

. RE LOC 


, LOC .DATA. 

PTR: .WORD TABLE 

TABLE: . B L K W 100 

. RELOC 

reserves space for four variables in the data segment. 
Plink-II can be instructed to load data segments and common 
blocks anywhere in memory via the SEGMENT statement. 
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Appendix F - The EXECUTE Utility 

PRC output files may be executed directly only under Phoenix 
Software Associates' PDOS operating system. The EXECUTE utility 
program is provided to allow them to be executed on any CP/M type 
operating system. 

To perform this action, enter EXECUTE followed by the 
standard command that would be given to execute the program 
normally. For instance, suppose a program named COPY.PRG is to 
be executed with two file names as arguments. On a PDOS system, 
the operator would enter 

COPY FILEA FILEB 

but on other systems, the operator would enter 

EXECUTE COPY FILEA FILEB 

The EXECUTE program loads the program for execution exactly 
as PDOS would, including the initialization of all memory areas 
from address zero to 100 hex. 

Sometimes it may be desirable to create a COM file that 
executes a particular PRO file, to save typing if a program is 
frequently used, or to create a program for unsophisticated 
users. EXECUTE per for rn s this function also, by giving as 
arguments a slash (/) followed by the name of the PRG file that 
will be executed, and the name of the COM file that will execute 
that particular PRG file. The COM file name and drive id default 
to the PRG file counterparts. Continuing with the above example, 

EXECUTE /COPY COPY 

would create a specialized version of the EXECUTE u t i 1 1 y named 
COPY.COM, which would be configured to execute the COPY.PRG file 
directly. This could have been abbreviated as 

EXECUTE /COPY 

since the COM file name defaults to the PRG file name. Note 
that the drive id given with the COM file name specifies what 
drive the COM file will be written to (logged-in disk if 
emitted), while the PRG drive id specifies on what drive the COM 
file will look for the PRG file (again, logged-in disk if 
omitted). For example, 

EXECUTE COPY B:C0PY 

creates a file COPY.COM on the B drive which, when executed, 
attempts to load COPY.PRG from the logged in disk. On the other 
hand , 


EXECUTE A : COPY B: 
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creates a file COPY.COM on the B drive which, when executed, 
attempts to load COPY. PR G from the A drive. 

This scheme thus offers a way to create programs for CP/M 
systems with many overlays that nevertheless consist of only two 
files: all of the program code and overlays are contained in a 
single FRG file. 
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Appendix G - The Overlay Loader 

It may occasionally be necessary to write your own overlay 
loader to create programs that run under a non-CP/M compatible 
operating system, or to be able to do memory- mapped overlays, for 
instance. This appendix gives the technical information 
necessary to accomplish this task. 

When a program contains overlays, Plink-II constructs a 
common block containing various tables for use by the overlay 
loader. This segment is named . 0 V T B . , and is formatted as 
follows : 


. OVTB . 


Overlay Table 


Overlaid 
Symbol Vectors 


INIT. : 

(initialization 

code) 

J M P .MAIN. 


The overlay loader module must be in a file of the proper 
name (see section on selecting overlay loader), and must have a 
module name of . 0 V L Y . It is automatically included in the 
program whenever a program contains overlays. When the program 
first begins execution, control is passed to the front of the 
overlay loader, which should initialize itself and then jump to 
label .INIT, The code here causes resident portions of the 
program which were not loaded by the operating system to be 
loaded by calling the .LOAD, entry point of the overlay loader 
with the overlay number in the A register. Execution of the 
actual program then begins via a jump to label .MAIN. 

The overlaid symbol vectors are routines that are used as 
the program executes. Their task is to call the overlay loader 
to insure that an overlay is in memory: 

CALL . 0 V L Y . 

.BYTE Coverlay if > 

.WORD < s y m b o 1 address > 

When the overlay loader is called at its . OVLY . entry point, 
it must load the given overlay (if not loaded already), and then 
jump to the given address. It must save and restore all user 
registers, and it is probably a good idea to use the program's 
stack as little as possible to avoid an overflow. 
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The symbol vectors are used whenever an overlaid symbol is 
called from a section that is not a descendant of or the same as 
the section containing the symbol. In other words, the user's 
code is not modified when a reference is made from a section to 
its ancestor. This allows overlays to access data in their 
ancestors. Therefore , the overlay loader must guarantee that 
when an overlay is in memory, all of its ancestors are in memory 

ci i 8 O , 


The overlay table contains the addresses needed to read the 
overlays from the .PRG file and ancestor information. It 
consists of a seven byte entry for each overlay, and the entries 
are implicitly numbered beginning with one. There are a maximum 
of 255 entries, each having the following format: 


Offset Size Contents 


3 

5 


1 Number of ancestor overlay, zero if none. 

2 Starting memory address 

2 Ending memory address 

2 Star- ting disk record (123 bytes/record) 


The table is ended by a dummy entry with a - 1 ( 2 5 5 H ) in the 
ancestor field. Note that there is no ending disk record number: 
the overlay loader must check the starting disk address of the 
following entry to determine the disk size of the overlay. This 
size is different from the memory size, because the disk size is 
synchronized to a record bound ry , and may be smaller than the 
memory size if there is uninitialized space at the end of the 
overlay. The last dummy entry in the table contains the record 
number of the end of the last overlay. 


The algorithm to read an overlay into memory might proceed 
as follows. The overlay loader maintains an FCB for the .PRG 
file (its name may be obtained from address 50 in memory during 
the initialization phase). This file is positioned to the 
starting record number either by calculating an extent and FCB 
record number or by using any random 1/0 capabilities offered by 
the operating system. Then disk reads are done until either the 
end of the overlay is reached on disk or until memory space runs 
out. I/O's may be done directly into the user's memory, except 
that the last one may not have a full 128 bytes of memory and 
will have to oe done in a separate buffer. 

The overlay loader should keep track of what overlays are 
currently in memory (via a bit map, for instance), so that the 
loading process can be skipped if the overlay is already present. 
When an overlay is loaded, the loader should then delete any 
other overlays overlapping it in memory by comparing the starting 
and ending memory addresses. 
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The remaining task faced by the loader is satisfying the 
rule described above that an overlay's ancestors must be in 
memory when it is. If the applications to be handled never use 
overlay structures more than one level deep, then none of the 
overlays have overlays for ancestors, so nothing need be done. 
Otherwise, the ancestor requirement can be handled via the 
following two steps. 

First, whenever an overlay is loaded, make sure its ancestor 
is loaded as well, and so on, until an overlay is encountered 
that is already loaded, or until the end of the ancestor chain is 
reached (ancestor number equal to zero). 

Second, whenever an overlay is deleted, mark all of its 
descendants deleted also. Due to the fact that the overlay table 
is constructed so that an overlay always has a number higher than 
its ancestor, this process can be combined with the overlap check 
described above. The loader loops through the overlay table from 
start to finish. Each overlay is first deleted if it has an 
ancestor that's deleted; otherwise, the check for overlap with 
the loaded overlay is made. The ordering of the table guarantees 
that an overlay is deleted before any of its decendants are 
encountered . 
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Appendix H - Command Syntax Summary 

This appendix defines Plink-II input syntax via a modified 
BNP for those familiar with formal computer languages. The 
symbol " : : = " means "is defined to be". Angle brackets delimit 
names of subsequent definitions. Everything else must be entered 
as shown, except that, key words may be abbreviated by truncating 
the lower case letters from the right. In any case, Piink-II 
translates any lower case letters in key words to upper case 
automatically. A vertical bar means choice: either of the items 

may be used. Sometimes, a set of alternatives is surrounded by 
parenthesis. Square brackets delimit. optional input. Curly 
braces indicate input which may be omitted, or included as often 
a s n e e d e d , 

< i n p u t > : : = (command> { ; <command> } 

< command) ::= <statement> f <statement}> 

< s t a t e m e n t > : : = 

! Output <fiie> 
i Report L = < f i 1 e > ] 

! (I Dent ! MAIn) <module> 

! PROGid <program> [ , <ver sion> ] 
i PDos <version> 

| MAP < o p t i o n > { , < o p t i o n > } 

I P A g e < b y t e > 

; D A t e 

| D E F i n e <definition> { , < d e f i n i t i o n > ) 

! (File J Library ! S E A r c h ) < f i 1 e > { , < f i 1 e > } 

! (CO N catenate ! SEGment) <segment> { , < segmen t> } 

! (MOdule ! INClude ! EXClude) <moduie> ! ,<module> ) 

! (LOcatelACtual) < e x p r > 

| SEC t i on < i d > 6 
i SCte n o 
i F R e e m e nor y 
I B E g i n a r e a 
! S H a r e 
1 OVer 1 a y 
! ENDarea 
! N o sort 
I .DATA. 

(DEBug i 18080) 

| Display <s-item> { , < s - i t e m > } 

| (GETVal ! GETChr PROMpt) <local> t.CR] 
i < 1 o c a 1 > : = < e x p r > 

I [IF < r e 1 a t i o n > ] ( G 0 1 o ! BAckto) < 1 a b e 1 > 

< 1 a b e 1 > : : = < i d > 8 ! < 1 o c a 1 > 

< m a p option)' : : = A 1 S ! G [ M 

(definition) ::= (symbol) = <expr> 

i <symbol> = <symboi> [(+!-) (expr) 3 
<s-i tern) ::= (literal) ! TAB | CR ! BEL ! [ HEX ! DECima 1 ] (expr) 

(version) : : - < b y t e > [ , < b y t e > ] 

<byte> : : = (expr) with m s b - F F or 00 
(relation) (expr) (r-op)[<r-op)j (expr) 

< r - o p > ::=<!>! = 
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< e x p r > : : 

< v a 1 u e > : 

< 1 o c a 1 > : 

<program> 
<module> 
<segment> 

< 3 y n b o 1 > 

< i d > : : = 


< f i 1 e > : : 
<literai> 


< n u m b e r > 


PSA Object Module Linkage Editor t 6 

H - Command Syntax Summary 

= < v a 1 u e > [(+ I - ! * i / I \ I & ! !) <value>] 

! - < v a 1 u e > 

:= < 1 o c a 1 > ! <number> J <literal>2 

:= #<value>, where value < = 50. 

: : = < id >6 
: : = < i d > 6 
: ; = [ " ] < i d > 8 
: : = < i d >8 

any string not beginning with a digit and 
not containing the following chars: 

= ;<>/, \ ! DEL 

= standard file name for operating system and 
not containing the chars: ''? = _;<>/, DEL 

::= Any character string delimited by single 
quotes. A quote character is included 
in a literal by entering two quotes. 

::= Any string beginning with a digit 0-9 
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Appendix I - Error Messages 

1 - " § " inside 0-file. Disk files containing commands and used 

via an " 0 " may not contain further "0" specifications. 

2 - "0" file is missing. The file name after an "0" 

specification doesn't exist. 

5 - Input token too large. The string of characters entered at 

this point is too large to be a keyword, name, or literal. 

6 - Invalid digit in number. Which digits are legal depends, 

of course, on the radix being used (default is hex). 

7 - Number too large. The given value can't be expressed as a 

16 bit quantity. 

10 - Invalid file name. The input stream should contain a valid 

file name for the particular operating system being used. 

11 - Expecting a statement. A key word which begins a statement 

should be present here. 

12 - Expecting " : = " . 

13 - Invalid output file type. The type of the file given in 

the OUTPUT statement must be .COM or .PRO. 

14 - Expecting identifier. A section, module, segment, or 

symbol name must be entered at this point. 

15 - Expecting "=" 

16 - Expecting a value. An expression or 16-bit quantity must 

a p p ear at t h is point. 

18 - Data segments of modules may not be used in the CONCATENATE 

statement, because they are unique to a particular module. 

19 - Expecting segment name. 


20 - Expecting byte value. The value used here must lie in the 

range 0 to 255 (or - 1 2 8 to 127 in signed notation). Than 
is, it must be possible to represent the value in 8 bits. 


2 1 

- The 

IF < r e 1 a t i o n > 

statement 

must 

be 

followed 

by a GOTO o>~ 


BAG 

K T 0 statement. 






22 

- The 

label used in 

a GOTO 

o r 

BACK 

TO statement does not 


e x i 

s t , 






2 3 

- I n v 

a 1 i d relational 

operator . 
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24 - Invalid DISPLAY item. 

25 - expecting CR in GETCHR , PROMPT, or GETVAL statement. 

26 - invalid local variable name. A local variable name is a 

pound sign followed by a value in the range 0-50. 

27 - Inconsistant statements for OUTPUT file type. Statements 

were used that imply a particular output file type, but a 

different type was specified. For instance, the OVERLAY 
statement may be used only with a .PRC file 

40 - No more memory. Plink-II ran out of memory for its 

internal tables and disk buffers; there!' ore, the program 
could not be linked. 

45 - Premature end of file. The end of the indicated .REL file 

was reached unexpectedly. Possibly, the .REL file was 
truncated by copying it with a program that assumes a 
CNTL-Z ( 1 A H ) is end of file. Try re-compiling. 

46 - No disk directory space for output file. 

47 - No more disk space for output file. 

48 - Protection violation in output file. 

49 - Can’t close output file. Was the floppy diskette changed 

before Plink-II finished execution? 

50 - Attempt to load to an absolute address. This error will 

occur if an attempt is made to .LOC to an absolute address 
in an assembler module and then load code or data. Use the 
LOCATE statement in Plink-II instead, making a common block 
out of the data that is to be loaded at a particular 
address . 

55 - A segment was mentioned in the MODULE, SEGMENT or 

CONCATENATE statements, but was never encountered in the 
input .REL files. 

60 - Undefined symbols exist. The listed symbols were external 

to one or more modules, but were never defined. They will 
have to be defined as internals of some module, or created 
via the DEFINE statement. 

61 - Symbol is self-defined. The given symbol was defined 

relative to a another symbol, and that symbol defined 
relative to yet another symbol, and so on, until the 
original symbol was reached again. Thus, a circular chain 
was created with no symbol actually ever being defined. 
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65 - The .ROOT, section may not be an overlay. 


6 6 

- Overlays 

are 

nested 

too deeply. The maximum 

n e s t i 

n g 1 e v e l 


is 32 ( i 

. e no 

m o r e 

than 3 2 B E G IN AK E A statement 

s in a y 

b e u s e d 


without 

enter 

i n g an 

ENDAREA statement). 



69 

- Too rn a n y 

ENDA 

REA s 

tatements. The number of 

t h e s e 

m u s t b e 


equal to 

the 

number 

of BEGIN AREA statements. 




6 8 - Not enough END A REA statements. The number- of these must be 

equal to the number of BEGIN AREA statements. 


69 - Too many overlays or overlay entry points. There may be a 

maximum of 255 overlays and about 9000 overlay entry 
p o i nts . 

70 - LOCATE error. The specified address overlaps previously 

loaded items. 

71 - Program address space is too large. The program will not 

fit into the address space of a 16-bit computer. 

72 - Either no modules were included in the linkage edit, or the 

entire program is overlaid. At least one section of the 
program must be permanently resident, and must contain 
s omething . 

7 3 - loading below address 1 0 0 H in .COM file. Since .COM files 

are always loaded at address 1 0 0 H by the operating system, 
nothing may be loaded below this address. 

7 4 - The OVERLAY arid OVERLAP statements may be used only inside 

a n o verlay area (BEGIN AREA/ ENDAREA) . 

78 - No FILE, LIBRARY or SEARCH statement has been given yet, so 

1 N C L U D E a n d EXCL U D E m ay no t b e used. 

79 - Can't INCLUDE and EXCLUDE from the same file. Only one of 

these statements may be used with a particular file. 

8C - Duplicate input file. Each file used in the FILE, SEARCH 
or LIBRARY statements must have a unique name. 

83 ~ The program starting address defined by a particular module 
may not be an absolute address, or a symbol external to 
that module. 

8 4 - T h e module mentioned in the MAIN statement was never 

encountered in the input . R E L files. 

85 - Missing starting address. The MAIN statement was not used, 

symbol .MAIN. did not exist, and none of the program 
modules had a defined starting address . 
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86 
9 1 

9 3 

94 
9 5 

96 

97 

100 

1 0 1 

102 
1 03 


.MAIN, may not be an absolute symbol, or an external 
symbol. It must be an INTERNAL symbol of some module. 

Invalid external byte reference. In the PSA macro 
assembler module named, an external byte reference (whose 
relocation base number is supplied) was made to a 
non -absolute symbol, or one with too large a value. 
External byte references may be made only to absolute 
symbols with a value in the range 0 to 255 (or -128 to 127 
in signed notation). 

Microsoft Commons overlap in memory. Due to the defined 
overlay structure, two or more Microsoft common blocks 
that are accessed by the same module overlap in memory. 
This is illegal because it makes "fix ups" to already 
loaded code Impossible. 

Too many common blocks in Microsoft module. A maximum of 
251 common blocks are allowed in each module. 

Invalid special link item in Microsoft file. This . R E L 
file is either smashed, or is not legally formed according 
to the Microsoft format, or represents a Microsoft Cobol 
program containing SECTION statements. 

invalid B field in Microsoft . R E L file. This field is 
supposed to contain an ascii name of up to 8 characters. 
The . R E L file is probably smashed: try re-compiling. 

More than one library search was called for in a Microsoft 
format module that is itself being library searched. This 
Microsoft format module was incorrectly generated and may 
not be linked. 

expecting PSA .REL module. This error often occurs when 
there is garbage at the end of the previous module in a 
library file. 

Invalid record type in PSA .REL file. The file is probably- 
smashed: try re-asserabiing. 

Expecting carriage return ( ODH ) in PSA .REL file. 

Expecting line -feed (OAH) in PSA .REL file. 


104 


Expecting identifier in PSA .REL file. 
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Diagnostic Errors 

Errors w i t h the f ol lowing numbers indicate that a bug i r 
Plink-II has occurred through no error on the user's part. Try 
running Plink-II again. If the error persists, please gather the 
relevant information (error message, Plink-II version, input 
files, etc.) and notify the sofware distributer from whom you 
obtained Plink-II. These error messages are documented only for 
completeness in this manual. 

150 - Too many files open simultaneously. 

151 - File de-allocation bug. 

155 - Relocation base is undefined. 

156 - Relocation base undefined for disk address. 

15 7 - Bad relocation base ( B S . S C T ) 

160 - Duplicate segment (SG.ADD). 

16 1 - Missing segment ( S G . F N D ) . 

162 - End of segment list (SG.FST, SG.NXT). 

16 3 - Segment not in assigned Section's segment list ( S G s e c t ) . 

16 4 - S e g m e n t undefined ( S G . 0 F F ) . 

170 - Missing symbol. 

171 - End of symbol list. 

172 - Undefined symbol. 

173 ~ Self-defined symbol. 

175 - End of Section list, 

180 - End of File list. 

181 - Module excluded/not included. 

185 - End of PSA ,REL module. 

190 - Microsoft fixup bug (FixLnk) 

191 - Microsoft C o b o 1 symbol bug (ModEnd). 

250 - Aborted command. 
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Update Notes for Version 1.10 

This note lists Plink-II bug fixes and enhancements effective with 
version 1.10. 

Bugs : 


- Some versions of the Digital Research PL/1 compiler generate 

invalid . REL files when an empty string is declared: 256 garbage 

bytes are written to the -.DATA. segment causing the linkage editor 
to overwrite the memory assigned to the following segment. This 
usually doesn’t matter since the next segment is typically from a 
module that hasn’t been loaded yet, but the problem may surface if 
some of Plink-II f s commands for moving segments around in the 
program are used (e,g. SEGMENT, MODULE, LOCATE). Another PL/ 1 

problem has been fixed: modules having no code in them are now 

handled correctly. These would sometimes cause fixup errors or 

missing code or data in the output file. 

- If more than 2 undefined segments exist (warning #555, Plink-II 

would die with diagnostic error #164. Now programs may be linked 
with undefined segments: they are ignored. This is useful for 

tasks such as the creation of overlay structures that are used in 
many programs where not all of the segments mentioned in the 
structure are used in each program. 

- DEFINE <symbol> = <local variable> would cause a syntax error. 
This has been corrected. 

- Common blocks would not be handled properly if they had the same 

name as a module: each instance of the common was assigned a 

different memory area. This situation is now handled properly. 

Microsoft apparently handled this problem in their Fortran by 

setting the high order bit in the first character of each common 

block name. Unfortunately , this means that Microsoft Fortran and 

Sasic modules may not be combined into the same program because the 
new Basic compiler does not set the bit. Plink-II can match the 
common names properly, but another Basic problem is described 
below . 

- The overlay loader would be incorrectly linked i ft a .COM program 
when the LOCATE command was used. This has been fixed. 


New Features: 


- When the LOCATE statement is used in a .PRG program a new section 
is created. Since only the main section is loaded by the operating 
system when the program is executed, Plink-II includes the overlay 
loader into the program to load the other sections before execution 
of the program begins. This action may now be inihibi ted by using 
the new PAD option provided with the LOCATE command. For example, 

LOCATE 3000, PAD 

causes the previous section to be filled out until it reaches 
address 3000. In this way, the next section is forced to be 
adjascent to the previous one and will be loaded at the same time 
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from disk: the overlay loader is not required. 

- The COMMON command has been added. It may be used to define the 
size of a common block to be larger than the definition of the 
common provided by any module. It also performs the function of 
the SEG command by placing the common block in the current section. 
The syntax is COMMON <name1> = <size1>, <name2> = <size2>, ... For 
example : 

COMMON Cl =100, C2 - #1 * 5 

The COMMON command may not be used on a .DATA, segment or error #18 
will result. Also, the COMMON and CONCATENATE statements should 
not be used on the same common or the results will be 

unpredic table . 

- The various overlay loaders selected via the DEBUG and 18080 

commands are now combined into a single library file called 
OVERLAY. REL instead of being in separate files. Each has a 
different module name: ,0VLZ, is the standard loader, .OVLD. is 

selected when the DEBUG command is used, and ,0VL8. when the 18080 
command is used. Older overlay .REL files should be discarded: 
they will no longer work. 

- Many people have reported problems with linking modules produced by 
Microsoft's new Basic compiler. Plink-II can now handle these. If 
the /0 switch is used in the Basic compiler (to avoid the. use of 
the runtime module) some of Plink-II’s special commands have to be 
used. 

The problem is that the initialization code in these Sasic programs 
attempts to clear the blank common (.BLNK.) and counts on having 
the data segment for the module ("BASIC) immediately following 
.BLNK. in memory in order to determine its ending address. 
Plink-II normally moves .BLNK. to the end of the section so that 
Fortran programs can access free memory; therefore, the clearing 
routine wipes out the operating system. 

The SEGMENT command of Plink-II can be used to specify that the 
named segments are to be allocated memory at the current load, 
address. Older versions of Plink-II always put .BLNK. at the end 
of the current section, but version 1.10 will not do this if .BLNK. 
is used in the SEGMENT command. Plink-II will move all 
uninitialized segments to the end of the section, and .BLNK, and 
"BASIC are normally uninitialized, so the N0S0RT command must also 
be used to inhibit this action. To sum up, entering 

SEGMENT .BLNK., "BASIC N0S0RT 

into the Plink-II command will cause the correct memory structure 
to be be generated. 

If the /0 switch is NOT used in the Basic compiler, the program is 
linked so as to use the runtime support module, and no extra 
Plink-II commands are required; everything is sorted into the 
correct order in memory. A .COM file must be specified for output, 
overlays may not be used, and the LOCATE, ACTUAL, and .DATA, 
commands should not be used. 


Plink-II: PSA Object Module Linkage Editor II 

Update Notes for Version 1.10 (9/16/81) 


3 


Valid Plink input files: 

The Microsoft relocatable file format has become an industry 
standard for Z80 - CP/M compiler output. However, several 

manufacturers are selling compilers which output files that look like 
Microsoft's, but actually contain subtle differences. Plink can 
handle some of these, but others will not work. Also, Microsoft 
periodically makes minor changes to the format in order to support 
new language features. 

The list below indicates which compilers have been checked out with 
Plink 3.28. Usually, lower numbered versions are also handled 
correctly. If a compiler you wish to use is not on this list, either 
insure that it outputs a format compatible with a listed one, or 
contact your software distributor . 

Microsoft : 

- Ccbol 4,01 (in 4.01, the SECTION statement may not be used). 

- Fortran 3-31 

- Basic 5.30 (see comments above). 


Cromeraco : 

- Cobol 3.01 

Digital Research 

- PL/1 1.3 (the indexed . IRL files are not supported: they will 

have to be converted to normal form with the LIB program). 

MT Microsystems : 

- Pascal MT+ 5-2 (.ERL files designed to be input to the 
disassembler are not supported). 

Whitesmiths 

- C 2.0 (see discussion in update letter for Plink-II 1.08) 


Ithaca In ter sy steins 
- Pascal/Z 3.0. 
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Output: .COM file or FSA .PRO file with overlays. The „PRG files execute 
directly only under the PDOS operating system, but a utility program is 
supplied to allow the® to be run in a CP/M type environment. Dual IK output 
buffers insure adequate execution speed, and any random 1/0 calls supported 
by the operating system are used. 

Memory Map: Plink-II can create 4 different reports: symbols sorted 
alphabetically, program segments sorted alphabetically, the entire program 
printed in address order, and program modules printed with date and ties 02 
creation and version number (PSA .REL files only). The reports may be 
written to the list device or a disk file. Variable page width is 
supported. The date and time is included (or systems not supporting date 
and time, blanks are used, or Plink-II can prompt the operator). 


- Common Blocks: Plink-II supports Fortran type common blocks, with no 

requirement that the largest instance of the common he input first. Also, 
•concatenated" common blocks may be created: in these commons, each module 

is allocated its own space in the common, instead of sharing tae space with 
other modules. This feature is useful for tasks such as creating a table 
where each entry in the table is contributed by a separate module. 


- Memory allocation; program modules are broken down into code, data, and 
common segments, re-grouped into "sections", and allocated at any memory 
address desired by the user. A symbol .END. is created to signify the free 
memory available to the program, and its location may be defined at any 
point. The free memory symbols used by the Microsoft an <1 Whitesmith formats 
are handled as well. Program sections may be set up to execute at. an 
address different than the lead address. 


- Library Search: Libraries of relocatable files may ba loaded in their 

entirety, or with specific modules included or excluded. They nay be 
searched, 30 that a module is included only if required by portions of the 
program already loaded. Each library file may be individually marked to be 
searched only once, or to be searched repetitively until all references to 
undefined symbols nave been satisfied. Library modules may be inserted 
enmasss into the main program or a particular overlay, or aav be separately 
allocated by the user to different program sections. 

- Overlays: any number of "tree- structured " overlay areas may b© created, to 

a maximum of 255 overlays and to a depth of 32 levels, and these may be 
overlapped in an arbitrary fashion to create non- tree-structured 
organizations. Each overlay can have any number of entry points. An 
overlay loader module is automatically included with the program. When an 
overlay entry symbol is accessed, the overlay and all of its "ancestors" in 
the overlay tree are automatically loaded. Ho source changes are required 
in the program nodules. The main program and all overlays are created with 
a single linkage edit, and output to a single file. Memory overhead is 
approximately 7 bytes per overlay, 6 bytes per overlay entry symbol and IK 
bytes for the overlay handier. Output file' disk space may be minimized by 
having Plink-II “sort" the uninitialized portions of each overlay to the 
end; these portions need not appear in the disk file. Versions of the 
overlay loader which run or. an 8080 and display debugging messages as the 
program executes are offered. Technical information "allowing user-created 
overlay loaders is supplied. 

» Control Statements: Fifty temporary 16 bit variables are supplied. These 

may be assigned values, simple arithmetic and logical expressions, or 
console input, and may be tested via relational operatora and branch 
instructions. Temporary variables, character strings, and simple 
expressions may be displayed on the console. 


Plink-II is a part of Phoenix Software Associates' systems software 
development package , Pdevelop-II. 


(*) PSA, Plink-II, PDOS, and Pdevelop-II are trademarks 
Associates Ltd. 



8080 is a trademark of Intel Corp. 

Z8Q is a trademark of Zilog 

CP/M Is a trademark of Digital Research 

TOM is a trademark of Technical Design Labs, 
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